DOC: Add missing docstrings #31047

galuhsahid · 2020-01-15T16:43:31Z

Added docstrings:

pandas.Index.has_duplicates
pandas.Index.is_all_dates
pandas.Index.name
pandas.Index.is_boolean
pandas.Index.is_floating
pandas.Index.is_integer
pandas.Index.is_interval
pandas.Index.is_mixed
pandas.Index.is_numeric
pandas.Index.is_object

There are some other docstrings left - I couldn't find the docstrings below in the code:

None:None:GL08:pandas.Index.names:The object does not have a docstring
None:None:GL08:pandas.Index.empty:The object does not have a docstring

I don't really understand what the function does so I'm leaving the docstring empty for now:

pandas/pandas/core/indexes/base.py:639:GL08:pandas.Index.view:The object does not have a docstring

cc @datapythonista

- pandas.Index.has_duplicates - pandas.Index.is_all_dates - pandas.Index.name - pandas.Index.is_boolean - pandas.Index.is_floating - pandas.Index.is_integer - pandas.Index.is_interval - pandas.Index.is_mixed - pandas.Index.is_numeric - pandas.Index.is_object

datapythonista

Great job, added few comments, but looks really great. Thanks!

datapythonista · 2020-01-15T16:52:27Z

pandas/core/indexes/base.py

+
+        Returns
+        -------
+        boolean


Suggested change

boolean

bool

https://pandas.io/docs/development/contributing_docstring.html#parameter-types

datapythonista · 2020-01-15T16:52:47Z

pandas/core/indexes/base.py

+
+        Returns
+        -------
+        boolean


Suggested change

boolean

bool

datapythonista · 2020-01-15T16:53:06Z

pandas/core/indexes/base.py

+
+        Returns
+        -------
+        boolean


Suggested change

boolean

bool

datapythonista · 2020-01-15T16:54:40Z

pandas/core/indexes/base.py

        return self.inferred_type in ["integer"]

    def is_floating(self) -> bool:
+        """
+        Check if the Index only consists of floats, NaNs, or
+        a mix of floats, integers, or NaNs.


First line should be a single line. More information can be added later, in other paragraphs. This is for the index pages, to display correctly.

https://pandas.io/docs/development/contributing_docstring.html#section-1-short-summary

datapythonista · 2020-01-15T16:54:47Z

pandas/core/indexes/base.py

+
+        Returns
+        -------
+        boolean


Suggested change

boolean

bool

datapythonista · 2020-01-15T16:55:25Z

pandas/core/indexes/base.py

+
+        Returns
+        -------
+        boolean


Suggested change

boolean

bool

pandas/core/indexes/base.py

datapythonista · 2020-01-15T16:57:18Z

pandas/core/indexes/base.py

+
+        Returns
+        -------
+        boolean


Suggested change

boolean

bool

datapythonista · 2020-01-15T16:57:34Z

pandas/core/indexes/base.py

+
+        Returns
+        -------
+        boolean


Suggested change

boolean

bool

datapythonista · 2020-01-15T16:58:02Z

pandas/core/indexes/base.py

+
+        Returns
+        -------
+        boolean


Suggested change

boolean

bool

datapythonista

Thanks @galuhsahid, great job!

jorisvandenbossche

Thanks a lot for those docstrings!!

Added a few comments / questions

jorisvandenbossche · 2020-01-15T21:12:02Z

pandas/core/indexes/base.py

+        Returns
+        -------
+        bool
+            Whether or not the Index has duplicate values.


For a case like this, this might be a bit duplicative with the first line.

Do we (or the validation script) always require an explanation of the return type?

Yes the validation script requires a description for return values. Related error code: 'RT03': 'Return value has no description'. I confirmed this by removing one of the explanations, leaving only the return type, and the error appears when I ran python3 scripts/validate_docstrings.py --errors=RT03

(this discussion is certainly not a blocker for this PR, to be clear)

@datapythonista what's your view on this? It's of course easiest to be consistent / have a clear rule in the validation. But personally, I find that it doesn't add any value in this specific case.

I agree it's probably a bit repetitive. I think it may add value, even if from the short summary and the the name of the function, it should be easier for most people to infer what is the output (what True and False mean), I guess beginners can appreciate having it explicit. It's difficult sometimes to know if what is obvious for us it's for other people.

In any case, assuming it literally doesn't add any value, with all the work we've got with docstrings, I would just simply move forward, since there are so many other things that I think are more important and worth more our time. I think this looks fine to me, even if the repetition is not ideal.

Duplicate content can also add noise, as you might need to read both to ensure you don't miss something.

Anyway, not a discussion to continue on this PR

jorisvandenbossche · 2020-01-15T21:13:43Z

pandas/core/indexes/base.py

+        is_interval : Check if the Index holds Interval objects.
+        is_mixed : Check if the Index holds data with mixed data types.
+
+        Returns


Nit: "Returns" section above the "See also"

jorisvandenbossche · 2020-01-15T21:14:46Z

pandas/core/indexes/base.py

+        >>> idx.is_integer()
+        False
+
+        >>> idx = pd.Index([1, 2, 3, 4.0])


In practice, this is the same as above, as this will be parsed into a FloatIndex. So if we want a third example, I would maybe rather shows strings (or just leave it out)

jorisvandenbossche · 2020-01-15T21:17:46Z

pandas/core/indexes/base.py

+        >>> idx.is_floating()
+        True
+
+        >>> idx = pd.Index([1, 2, 3, 4.0, np.nan])


Same comment here as above.

I understand that from looking at the lists that are used to create the index, it looks like different cases, but all those are Float64Index objects. So for this case, I find it makes it actually more confusing (it would be rather an example to show in the main Index docstring to illustrate the constructor).

Thoughts?

Showing that it can contain NaN is of course useful.

I see; I was thinking by showing it, people who are not familiar with Float64Index objects will now what to expect, but I do agree that it's probably better to be an example to show in the main Index docstring. Will modify it & leave the NaNs

jorisvandenbossche · 2020-01-15T21:18:32Z

pandas/core/indexes/base.py

+        -------
+        bool
+            Whether or not the Index only only consists of numeric
+        data.


Suggested change

data.

data.

datapythonista · 2020-01-16T02:06:37Z

If you have a look at the CI, there are couple of errors in the docstrings that are making it fail: https://github.com/pandas-dev/pandas/pull/31047/checks?check_run_id=391576648#step:10:24

WillAyd · 2020-01-16T19:47:34Z

pandas/core/indexes/base.py

+        True
+
+        >>> idx = pd.Index([1, 2, 3, 4])
+        >>> idx.is_integer()


Suggested change

>>> idx.is_integer()

>>> idx.is_floating()

I think this is a typo

jorisvandenbossche · 2020-01-17T13:27:48Z

@galuhsahid Thanks a lot!

galuhsahid added 2 commits January 15, 2020 23:35

DOC: Add missing docstrings

e66ed48

- pandas.Index.has_duplicates - pandas.Index.is_all_dates - pandas.Index.name - pandas.Index.is_boolean - pandas.Index.is_floating - pandas.Index.is_integer - pandas.Index.is_interval - pandas.Index.is_mixed - pandas.Index.is_numeric - pandas.Index.is_object

DOC: Add is_all_dates and name

69f4ec0

simonjayhawkins added the Docs label Jan 15, 2020

datapythonista reviewed Jan 15, 2020

View reviewed changes

DOC: Fix bools, add See More

3b796fd

datapythonista approved these changes Jan 15, 2020

View reviewed changes

jorisvandenbossche reviewed Jan 15, 2020

View reviewed changes

DOC: Remove typos and some examples

dcab448

WillAyd requested changes Jan 16, 2020

View reviewed changes

WillAyd added this to the 1.1 milestone Jan 16, 2020

DOC: Fix typo

755a0f7

jorisvandenbossche approved these changes Jan 17, 2020

View reviewed changes

jorisvandenbossche merged commit a72eef5 into pandas-dev:master Jan 17, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Add missing docstrings #31047

DOC: Add missing docstrings #31047

galuhsahid commented Jan 15, 2020 •

edited

Loading

datapythonista left a comment

datapythonista Jan 15, 2020

datapythonista Jan 15, 2020

datapythonista Jan 15, 2020

datapythonista Jan 15, 2020

datapythonista Jan 15, 2020

datapythonista Jan 15, 2020

datapythonista Jan 15, 2020

datapythonista Jan 15, 2020

datapythonista Jan 15, 2020

datapythonista left a comment

jorisvandenbossche left a comment

jorisvandenbossche Jan 15, 2020

galuhsahid Jan 16, 2020

jorisvandenbossche Jan 16, 2020

datapythonista Jan 16, 2020

jorisvandenbossche Jan 17, 2020

jorisvandenbossche Jan 15, 2020

jorisvandenbossche Jan 15, 2020

jorisvandenbossche Jan 15, 2020

galuhsahid Jan 16, 2020

jorisvandenbossche Jan 15, 2020

datapythonista commented Jan 16, 2020

WillAyd Jan 16, 2020

jorisvandenbossche commented Jan 17, 2020

DOC: Add missing docstrings #31047

DOC: Add missing docstrings #31047

Conversation

galuhsahid commented Jan 15, 2020 • edited Loading

datapythonista left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

datapythonista left a comment

Choose a reason for hiding this comment

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

datapythonista commented Jan 16, 2020

Choose a reason for hiding this comment

jorisvandenbossche commented Jan 17, 2020

galuhsahid commented Jan 15, 2020 •

edited

Loading